클로드 코드 완벽 가이드 — 13장 에이전트 병렬로 실행하기 딥다이브 학습 노트
출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호) | 참고: https://github.com/codefactory-co
13장에서 다루는 내용
- 서브에이전트 — 메인에이전트가 작업을 위임하는 하위 에이전트의 개념과 동작 원리
- 병렬 실행 — 독립적인 작업을 서브에이전트로 동시에 처리하는 방법
- 직렬 실행 — 콘텍스트 효율을 위해 서브에이전트를 순차적으로 생성하는 방법
- 커스텀 서브에이전트 — /agent 커맨드로 맞춤형 서브에이전트를 정의하고 활용하는 방법
- 독립 에이전트 — Git Worktree를 활용하여 여러 에이전트를 완전히 독립된 환경에서 병렬 실행하는 방법
전체 흐름도
[에이전트 병렬 실행 파이프라인]
+------------------+ +------------------+ +---------------------+
| 1. 서브에이전트 | | 2. 병렬 실행 | | 3. 직렬 실행 |
| 개념 이해 | --> | | --> | |
| | | - 독립 작업 분리 | | - 콘텍스트 200K |
| - 메인이 생성 | | - 동시에 처리 | | 제한 관리 |
| - 작업 위임 | | - 번역/테스트/ | | - 순차적 서브에이전 |
| - 결과만 반환 | | 디자인 등 | | 트 생성 |
+------------------+ +------------------+ | - 결과만 반환 |
+---------------------+
|
+-----------------------------+
v
+---------------------+ +---------------------+
| 4. 커스텀 | | 5. 독립 에이전트 |
| 서브에이전트 | | |
| | | - Git Worktree로 |
| - /agent 커맨드 | | 작업 환경 분리 |
| - .claude/agents/ | | - 여러 터미널에서 |
| - 프론트매터 설정 | | 동시 실행 |
| - 자동/수동 트리거 | | - 머지 컨플릭트 |
+---------------------+ | 관리 필요 |
+---------------------+
선수 지식 체크리스트
- [ ] 클로드 코드 기본 사용법 (프롬프트, 도구 사용)
- [ ] 콘텍스트 윈도우 개념 (토큰 제한, Auto Compact)
- [ ] Git 기본 명령어 (branch, merge, worktree)
- [ ] 터미널에서 여러 창 동시에 사용하는 방법
핵심 키워드
| 키워드 | 의미 |
|---|---|
| 서브에이전트(Subagent) | 메인 클로드 코드 에이전트가 특정 작업을 위임하기 위해 생성하는 하위 에이전트. 별도의 200K 콘텍스트를 가짐 |
| 병렬 실행(Parallel) | 여러 서브에이전트를 동시에 실행하여 독립적인 작업을 한꺼번에 처리하는 방식 |
| 직렬 실행(Serial) | 서브에이전트를 하나씩 순차적으로 생성하여 콘텍스트를 효율적으로 관리하는 방식 |
| 커스텀 서브에이전트 | /agent 커맨드 또는 마크다운 파일로 미리 정의해둔 맞춤형 서브에이전트 |
| 프론트매터(Frontmatter) | 마크다운 파일 최상단 --- 사이에 name, description, color 등 메타데이터를 저장하는 영역 |
| Git Worktree | 하나의 Git 저장소에서 여러 작업 디렉토리(워크스페이스)를 생성하는 기능 |
| 독립 에이전트 | 서브에이전트가 아니라 완전히 별도의 클로드 코드 인스턴스로 실행되는 에이전트 |
| Todo 리스트 | 클로드 코드가 작업 진행 상황을 체크박스로 정리한 작업 목록 |
| 콘텍스트(Context) | AI 에이전트가 대화에서 참조하는 전체 맥락. 200K 토큰이 최대 제한(2025년 7월 기준) |
섹션 1: 서브에이전트 개념
한 줄 요약
서브에이전트는 메인 에이전트가 작업을 위임하기 위해 생성하는 하위 에이전트로, 병렬 또는 직렬로 실행할 수 있다.
쉬운 설명 (비유)
서브에이전트는 "팀장과 팀원" 관계와 같다.
팀장(메인에이전트):
- 전체 프로젝트를 관리하고 큰 그림을 봄
- 작업을 나눠서 팀원들에게 할당
- 팀원이 보고한 결과만 확인하면 됨
팀원(서브에이전트):
- 팀장이 지시한 작업만 독립적으로 수행
- 이전 회의(콘텍스트) 내용을 모르고 새로 시작
- 작업 끝나면 결과만 팀장에게 보고
핵심: 팀원이 100페이지 보고서를 작성해도
팀장은 3줄 요약만 받으니 부담이 없다!
실무 예제: 서브에이전트 자동 생성 확인
클로드 코드에게 큰 작업을 시키면 자동으로 서브에이전트 생성:
사용자 프롬프트:
"테스트를 실행하고 커버리지를 개선해줘"
클로드 코드 화면:
● Task(테스트 실행 및 커버리지 개선)
└ Initializing... <-- 서브에이전트가 생성되는 중!
작업 완료 후:
● Task(테스트 실행 및 커버리지 개선)
└ Done (70 tool uses · 127.6k tokens · 12m 19.6s)
* Forming... (754s · ↑ 215 tokens · esc to interrupt)
핵심 포인트:
- 서브에이전트가 127.6K 토큰을 사용했지만
- 메인에이전트는 215 토큰만 소비!
- 즉, 127K 이상의 콘텍스트를 절약한 것
핵심 체크포인트
- 서브에이전트는 메인에이전트가 작업을 위임하기 위해 생성하는 별도의 에이전트
- 서브에이전트는 새로운 200K 콘텍스트를 가지므로 메인의 콘텍스트를 절약
- 메인에이전트는 서브에이전트의 작업 결과 요약만 받아서 워크플로를 제어
- 클로드 코드가 자동으로 서브에이전트를 생성하기도 하고, 프롬프트로 명시적으로 지시할 수도 있음
섹션 2: 병렬 실행
한 줄 요약
서로 독립적인 작업(번역, 테스트, 디자인 등)을 여러 서브에이전트에 동시에 맡겨서 시간을 크게 절약할 수 있다.
쉬운 설명 (비유)
병렬 실행은 "식당 주방"과 같다.
❌ 직렬 방식 (1명이 모든 요리):
스프 만들기 (10분) -> 스테이크 굽기 (15분) -> 디저트 만들기 (10분)
= 총 35분
✅ 병렬 방식 (3명이 동시에):
요리사A: 스프 만들기 (10분) ─┐
요리사B: 스테이크 굽기 (15분) ├─ 동시 진행 = 총 15분!
요리사C: 디저트 만들기 (10분) ─┘
주의: 스프에 스테이크 육수가 필요하면?
-> 스프와 스테이크는 의존성이 있어서 병렬로 못 함!
-> 독립적인 작업만 병렬로 처리해야 함
실무 예제: 다국어 번역 병렬 처리
프롬프트:
# 역할
너는 지금부터 다국어 번역 전문가야.
웹사이트 홈페이지를 영어, 일본어, 중국어, 아랍어로 번역하는 걸 도와줘.
# 작업 순서
- 번역해야할 텍스트를 전부 찾아줘
- 찾은 텍스트를 영어, 일본어, 중국어, 아랍어로 번역해줘.
- 각 언어별로 subagent 4개를 동시에 생성해서 평행으로 (parallel) 작업해줘
- subagent에게 "너는 지금부터 다국어 번역 전문가야.
이 위치의 문장들을 ${언어}로 번역해줘"라고 프롬프팅 해줘
- 번역 외에 다른 작업은 절대 하지 말아줘
- 모든 작업이 끝났다면 테스트, 린트, 빌드를 실행하고 에러가 없는지 확인해줘.
클로드 코드의 실행 결과:
● Update Todos
□ 홈페이지에서 번역할 텍스트 찾기
□ 영어로 번역 (subagent) ─┐
□ 일본어로 번역 (subagent) ├─ 4개가 동시에 실행!
□ 중국어로 번역 (subagent) │
□ 아랍어로 번역 (subagent) ─┘
□ 테스트, 린트, 빌드 실행 및 에러 확인
병렬 실행에 적합한 작업들
✅ 병렬로 실행하면 좋은 작업:
- 다국어 작업할 때 여러 언어로 동시에 병렬로 번역
- 많은 분량의 테스트를 독립적으로 나눠서 동시에 병렬로 작업
- 여러 디자인 시안을 동시에 병렬로 작업할 때
- 깃허브 이슈 여러 개를 동시에 생성하고 싶을 때
❌ 병렬로 하면 안 되는 작업:
- 작업 B가 작업 A의 결과에 의존하는 경우
- 같은 파일을 여러 에이전트가 동시에 수정하는 경우
- 순서가 중요한 데이터 처리 (ETL 파이프라인 등)
핵심 체크포인트
- 병렬 실행은 독립적인 작업을 동시에 처리할 때 효율적
- 작업 간 충돌이 발생하면 아무리 병렬로 많이 처리해도 느려질 수 있음
- 프롬프트에 "subagent로 병렬(parallel) 작업해줘"라고 명시
- 토큰은 서브에이전트 수만큼 더 소비되지만, 시간 절약 가치가 훨씬 큼
섹션 3: 직렬 실행
한 줄 요약
직렬 실행은 서브에이전트를 하나씩 순차적으로 생성하여, 콘텍스트 200K 제한을 효율적으로 관리하면서 대규모 작업을 처리하는 방법이다.
쉬운 설명 (비유)
직렬 실행은 "릴레이 달리기"와 같다.
메인에이전트 = 감독
서브에이전트 = 주자
감독: "1번 주자, 첫 번째 구간 뛰어!"
1번 주자: (200m 달림) -> 결과를 감독에게 보고
감독: "좋아. 2번 주자, 두 번째 구간 뛰어!"
2번 주자: (200m 달림) -> 결과를 감독에게 보고
감독: "마지막. 3번 주자, 세 번째 구간 뛰어!"
3번 주자: (200m 달림) -> 결과를 감독에게 보고
핵심: 각 주자(서브에이전트)는 자기 구간만 뛰고
감독(메인에이전트)은 바통(결과 요약)만 전달받음
-> 감독의 체력(콘텍스트)은 거의 소모되지 않음!
실무 예제: CRUD 엔드포인트 직렬 구현
하나의 에이전트가 4가지 CRUD를 모두 처리하면:
- 컨트롤러, 서비스, 리포지터리 전부 다루어야 함
- 클린 아키텍처라면 믿기 힘들 정도로 복잡해짐
- 빌드/테스트/린트/커밋/풀리퀘스트까지 불가능
직렬 서브에이전트로 나누면:
+-------------------+
| 메인에이전트 |
| (워크플로 제어) |
+-------------------+
|
v
+-------------------+
| 서브에이전트 1 | 부분 작업 1 전달
| Create 엔드포인트 | ----> 결과 요약 후 메인에 반환
+-------------------+
|
v
+-------------------+
| 메인에이전트 | 결과 확인 후 다음 작업 전달
+-------------------+
|
v
+-------------------+
| 서브에이전트 2 | 부분 작업 2 전달
| Read 엔드포인트 | ----> 결과 요약 후 메인에 반환
+-------------------+
|
v (Update, Delete도 동일한 패턴)
장점: 메인에이전트는 워크플로 제어만 하고
실무는 서브에이전트에게 넘겨서 효율적!
직렬 실행을 사용해야 하는 상황
❌ 병렬 실행이 비효율적인 경우:
- 200K 토큰을 넘길 정도의 대규모 작업
- 하나의 에이전트가 감당하기 어려운 복잡한 코드
✅ 직렬 실행이 유리한 경우:
- 대규모 CRUD 엔드포인트 제작
- 테스트/린트/빌드의 출력이 매우 많을 때
- 메인에이전트 콘텍스트를 아끼고 싶을 때
프롬프트 예시:
"테스트를 subagent에서 독립적으로 실행하고
subagent에게 'pnpm run test를 실행해서 테스트를 실행하고
에러가 있다면 에러를 해결해줘. 커버리지는 80% 이상이
될 수 있도록 테스트가 추가로 필요하다고 생각하는 곳에
테스트를 더 작성해줘'라고 전달해줘"
핵심 체크포인트
- 직렬 실행은 AI 에이전틱 프로그래밍에서 병렬보다 더 자주 사용되는 테크닉
- 콘텍스트 200K 제한을 효율적으로 관리하는 핵심 전략
- 서브에이전트는 결과만 메인에 반환하므로 콘텍스트 절약 효과가 큼
- 클로드 코드가 이미 내부적으로 직렬 에이전트 기능을 사용 (Task 키워드)
섹션 4: 커스텀 서브에이전트
한 줄 요약
/agent 커맨드로 커스텀 서브에이전트를 미리 정의해두면, 특정 작업(테스트, 코드리뷰 등)에 최적화된 전문가 에이전트를 반복적으로 활용할 수 있다.
쉬운 설명 (비유)
기본 서브에이전트 vs 커스텀 서브에이전트
기본 = 파견 직원
- 매번 새로 와서 "뭘 해야 하죠?" 물어봄
- 회사 규칙/도구를 모르니 매번 설명해야 함
- 그래도 일은 해줌
커스텀 = 전문 팀원
- 채용 시 "테스트 전문가"로 역할이 정해져 있음
- pnpm test가 우리 회사 테스트 도구인 줄 앎
- 커버리지 80% 기준도 미리 알고 있음
- 별도 설명 없이 바로 최적의 작업 수행!
실무 예제: 커스텀 서브에이전트 생성 과정
Step 1: /agent 커맨드 실행
> /agent
Step 2: 새로운 에이전트 선택
> Create new agent
Step 3: 저장 위치 선택
1. Project (.claude/agents/) <-- 프로젝트 전체에서 사용
2. Personal (~/.claude/agents/) <-- 나만 사용
Step 4: 생성 방법 선택
1. Generate with Claude (recommended) <-- 클로드가 자동 생성
2. Manual configuration <-- 수동으로 직접 작성
Step 5: 역할 설명 입력 (예시)
"테스트할 때 테스트 실패하는 요소들이 있으면 수정하고
테스트 커버리지를 80% 이상으로 끌어올리는 에이전트를 생성해줘."
Step 6: 도구 선택
☑ All tools <-- 모든 도구 사용 가능
☑ Read-only tools
☑ Edit tools
☑ Execution tools
☑ MCP & Other tools
Step 7: 색상 선택
Red / Blue / Green / Yellow / Purple / Orange / Pink / Cyan
Step 8: 확인 및 저장
Name: test-coverage-optimizer
Location: .claude/agents/test-coverage-optimizer.md
Tools: All tools
결과: .claude/agents/ 폴더에 마크다운 파일 생성!
커스텀 서브에이전트 마크다운 파일 구조
파일 위치: .claude/agents/test-coverage-optimizer.md
--- (프론트매터 시작)
name: test-coverage-optimizer
description: Use this agent when you need to fix failing tests
and improve test coverage to 80% or higher. ...
color: red
--- (프론트매터 끝)
(아래에 프롬프트 내용 작성)
You are a Test Coverage Optimization Specialist, an expert
in comprehensive test strategy, failure analysis, and
systematic coverage improvement...
프론트매터 변수 정리:
+-------------+------------------------------------------------+
| 변수 | 설명 |
+-------------+------------------------------------------------+
| name | 서브에이전트의 이름 |
| description | 서브에이전트 설명. 클로드가 어떤 서브에이전트를 |
| | 사용할지 이 필드로 판단 |
| color | 서브에이전트가 실행될 때 쉽게 식별할 색상 |
+-------------+------------------------------------------------+
커스텀 서브에이전트 트리거 방법
방법 1: 자동 트리거 (클로드가 description을 보고 판단)
프롬프트: "서브에이전트를 사용해서 유닛 테스트를 실행주고 커버리지를 올려줘."
-> 클로드가 description을 분석해서 test-coverage-optimizer 자동 선택
방법 2: 이름 명시 (강제 트리거)
프롬프트: "test-coverage-optimizer를 사용해서 테스트를 실행하고 커버리지를 올려줘."
-> 이름을 직접 지정하여 해당 커스텀 서브에이전트를 무조건 실행
Tip: 트리거가 잘 안 되면 description을 더 상세하게 작성하거나
이름을 직접 명시하는 방법을 사용!
핵심 체크포인트
- /agent 커맨드로 생성하고, .claude/agents/ 폴더에 마크다운 파일로 저장됨
- 프론트매터에 name, description, color를 설정
- description이 중요: 클로드가 어떤 서브에이전트를 트리거할지 이 필드로 판단
- 사용자 스코프(Personal) 또는 프로젝트 스코프(Project) 선택 가능
- 현재 자동 생성은 영어만 지원하지만, 생성 후 한국어로 번역 가능
섹션 5: 커스텀 서브에이전트 활용 사례
한 줄 요약
테스트 에이전트, 아키텍처 레이어별 에이전트 등 목적에 맞는 커스텀 서브에이전트를 만들어두면 반복 작업에서 콘텍스트를 절약하고 일관된 품질을 유지할 수 있다.
쉬운 설명 (비유)
커스텀 서브에이전트 = 전문 부서
회사 조직도처럼 역할별 전문 부서를 만드는 것:
+-------------------+
| CEO (메인에이전트) |
+-------------------+
| | |
v v v
+-------+ +--------+ +----------+
| QA팀 | | UI팀 | | DB팀 |
| 테스트| | Shadcn | | 스키마 |
| 전문 | | 전문 | | 절대 안 |
| | | Tanstack| | 건드림 |
+-------+ +--------+ +----------+
각 부서는 자기 전문 분야만 담당하고,
CEO(메인에이전트)는 조율만 하면 됨!
실무 예제: 다양한 커스텀 서브에이전트
1. 테스트 에이전트
- 테스트 실행, 실패 수정, 커버리지 80% 이상 달성
- 메인에이전트의 콘텍스트를 소비하지 않음
- 결과(통과/실패)만 메인에게 보고
2. 아키텍처 레이어별 에이전트
- UI 생성 시: 항상 Shadcn UI, Tanstack Table 사용
- 테이블 생성 시: 반드시 특정 라이브러리 사용
- 서브에이전트가 실행될 때마다 제약사항이 콘텍스트에 자동 주입
3. 하면 안 되는 작업 명시하기
❌ 잘못된 예: 데이터베이스 관련 서브에이전트에게 스키마 변경 허용
✅ 올바른 예: "절대 스키마를 직접 생성하지 말고
가이드라인만 마크다운 파일로 생성하라"
-> 실수로 DB 스키마를 건드리는 사고 방지!
핵심 체크포인트
- 테스트 에이전트: 메인 콘텍스트 소비 없이 테스트 결과만 받기
- 아키텍처 레이어별 에이전트: UI/DB 등 레이어별 제약사항을 자동 주입
- "하면 안 되는 작업" 명시: 서브에이전트가 위험한 작업을 하지 못하도록 방지
- description을 상세하게 쓸수록 자동 트리거 정확도가 높아짐
섹션 6: 독립 에이전트와 Git Worktree
한 줄 요약
여러 터미널에서 클로드 코드를 동시에 실행하되, Git Worktree로 작업 환경을 분리하면 파일 충돌 없이 한 프로젝트의 여러 기능을 병렬로 개발할 수 있다.
쉬운 설명 (비유)
독립 에이전트는 "여러 개발자가 동시에 일하는 것"과 같다.
서브에이전트 = 한 사무실에서 팀장 지시를 받는 팀원
독립 에이전트 = 각자 다른 사무실에서 독립적으로 일하는 개발자
문제: 같은 사무실(프로젝트)에서 두 개발자가 동시에 같은 파일을 수정하면?
-> 충돌 발생! 서로의 작업을 덮어쓸 수 있음
해결: Git Worktree
-> 같은 프로젝트를 물리적으로 복사하되 Git이 관리
-> 개발자A는 프론트엔드 폴더에서, 개발자B는 백엔드 폴더에서 작업
-> 작업 끝나면 Git merge로 합치기
비유하면:
프로젝트 = 원본 문서
Worktree = 복사본 (수정해도 원본 안 바뀜)
merge = 복사본의 수정사항을 원본에 반영
실무 예제: Git Worktree로 병렬 개발
1. 작업 분리 계획
프론트엔드 작업 + 백엔드 작업을 동시에 진행하고 싶다!
2. 워크트리 생성
# 프론트엔드 워크트리
git worktree add ../frontend
# 백엔드 워크트리
git worktree add ../backend
3. 각 터미널에서 독립적으로 클로드 코드 실행
터미널 1: cd ../frontend && claude
"프론트엔드 UI 컴포넌트를 만들어줘"
터미널 2: cd ../backend && claude
"백엔드 API 엔드포인트를 만들어줘"
4. 작업 완료 후 병합
# 메인 브랜치에서 merge
git merge frontend-branch
git merge backend-branch
5. 워크트리 정리 (중요!)
git worktree remove ../frontend
git worktree remove ../backend
# 만약 폴더를 직접 삭제했다면:
git worktree prune <-- 남은 워크트리 정보 정리
Git Worktree 명령어 정리
+------------------------------------------+-----------------------------------+
| 명령어 | 설명 |
+------------------------------------------+-----------------------------------+
| git worktree add [폴더위치] | 워크트리 생성 (브랜치명=폴더명) |
| git worktree add [폴더위치] [브랜치이름] | 워크트리 생성 + 브랜치명 지정 |
| git worktree add [폴더위치] -b [브랜치] | 새 브랜치를 만들면서 워크트리 생성 |
| git worktree remove [폴더위치] | 워크트리 삭제 (반드시 이걸로!) |
| git worktree prune | 폴더 직접 삭제 후 남은 정보 정리 |
| git worktree list | 현재 워크트리 목록 확인 |
+------------------------------------------+-----------------------------------+
독립 에이전트 사용 시 주의사항
❌ 흔한 실수:
- 같은 파일을 두 에이전트가 동시에 수정 -> 충돌!
- 워크트리 사용 후 git worktree remove 안 함 -> 워크트리 정보 꼬임
- 에이전트 간 MCP 브릿지로 소통 시도 -> 서브에이전트가 더 효율적
✅ 올바른 사용법:
- 각 에이전트를 "주니어 개발자 하나"로 생각
- 작업 환경을 충분히 격리 (프론트/백, 레이어별)
- 머지 컨플릭트 가능성을 미리 고려
- 작업 끝나면 반드시 워크트리 정리
핵심 체크포인트
- 독립 에이전트는 여러 터미널에서 클로드 코드를 동시에 실행하는 방식
- Git Worktree로 같은 프로젝트를 물리적으로 분리하여 충돌 방지
- 여러 프로젝트를 동시에 작업하거나, 한 프로젝트의 여러 기능을 동시 개발할 때 사용
- 작업 완료 후 반드시
git worktree remove로 정리해야 함 - 에이전트 하나하나를 주니어 개발자라고 생각하고 작업을 분리하는 것이 핵심
연습문제
문제 1: 병렬 vs 직렬 판단 (기본)
Q. 다음 작업들을 병렬 실행 또는 직렬 실행 중 어떤 방식이 적합한지 판단하고 이유를 설명하시오. - (A) 웹사이트를 영어, 일본어, 중국어로 동시에 번역 - (B) 데이터베이스 스키마를 만들고, 그 스키마에 맞는 API 엔드포인트를 개발 - (C) 10개의 독립적인 유닛 테스트 파일을 동시에 실행
정답 보기
- **(A) 병렬 실행**: 각 언어의 번역은 서로 독립적이므로, 서브에이전트 3개를 동시에 생성하여 동시에 번역 가능. 하나의 언어 번역이 다른 언어에 영향을 주지 않음. - **(B) 직렬 실행**: API 엔드포인트는 DB 스키마에 의존하므로 스키마가 먼저 완성되어야 함. 서브에이전트1이 스키마를 만들고, 그 결과를 바탕으로 서브에이전트2가 API를 개발해야 함. - **(C) 병렬 실행**: 각 테스트 파일이 독립적이므로 동시에 실행 가능. 단, 같은 데이터베이스를 공유하는 등의 의존성이 있다면 직렬이 더 안전함. 핵심 원칙: **작업 간 의존성이 없으면 병렬, 있으면 직렬**.문제 2: 커스텀 서브에이전트 설계 (중급)
Q. 코드 리뷰 전문 커스텀 서브에이전트를 설계하시오. 프론트매터(name, description, color)와 역할 프롬프트의 핵심 내용을 작성하시오.
정답 보기
---
name: code-reviewer
description: Use this agent when you need to review code changes
for best practices, security issues, and performance problems.
Triggers on code review, PR review, or quality check requests.
color: blue
---
You are a Code Review Specialist. Your core responsibilities:
1. **코드 품질 분석**
- 변수명/함수명이 의미를 잘 전달하는지 확인
- 불필요한 중복 코드 찾기
- SOLID 원칙 준수 여부 확인
2. **보안 취약점 검토**
- SQL 인젝션, XSS 등 보안 이슈 확인
- 하드코딩된 비밀번호/API 키 감지
3. **성능 문제 점검**
- N+1 쿼리 등 성능 문제 감지
- 불필요한 렌더링/연산 확인
4. **절대 하지 말 것**
- 코드를 직접 수정하지 말 것 (리뷰만!)
- 마크다운 리포트로 결과만 출력할 것
핵심: description을 상세하게 작성하여 클로드가 자동으로 트리거할 수 있도록 하고, "하면 안 되는 작업"을 명시하여 실수를 방지한다.
문제 3: Git Worktree 실무 시나리오 (심화)
Q. 쇼핑몰 프로젝트에서 프론트엔드(상품 목록 UI)와 백엔드(주문 API)를 동시에 개발하려고 한다. Git Worktree를 사용하여 두 에이전트를 병렬로 실행하는 전체 과정을 명령어와 함께 작성하시오. 작업 완료 후 정리 과정도 포함할 것.
정답 보기
# 1. 현재 메인 브랜치에서 시작
git checkout main
# 2. 프론트엔드 워크트리 생성 (새 브랜치 생성)
git worktree add ../shop-frontend -b feature/product-list-ui
# 3. 백엔드 워크트리 생성 (새 브랜치 생성)
git worktree add ../shop-backend -b feature/order-api
# 4. 터미널 1에서 프론트엔드 에이전트 실행
cd ../shop-frontend
claude
# 프롬프트: "상품 목록 UI 컴포넌트를 만들어줘"
# 5. 터미널 2에서 백엔드 에이전트 실행
cd ../shop-backend
claude
# 프롬프트: "주문 REST API 엔드포인트를 만들어줘"
# 6. 두 작업 모두 완료 후 메인 브랜치에서 병합
cd 원래프로젝트
git checkout main
git merge feature/product-list-ui
git merge feature/order-api
# 7. 워크트리 정리 (반드시!)
git worktree remove ../shop-frontend
git worktree remove ../shop-backend
주의사항:
- 프론트엔드와 백엔드가 같은 파일을 수정하면 머지 컨플릭트 발생 가능
- 작업 전에 "어떤 파일을 누가 수정할지" 미리 분리 계획을 세워야 함
- 워크트리를 삭제하지 않으면 Git 히스토리에 불필요한 정보가 남음
- `git worktree prune`으로 이미 삭제된 폴더의 잔여 정보를 정리 가능
부록 A: 용어 사전
| 용어 | 설명 |
|---|---|
| 서브에이전트(Subagent) | 메인 클로드 코드 에이전트가 특정 작업을 위임하기 위해 생성하는 하위 에이전트. 독립적인 콘텍스트를 가짐 |
| 메인에이전트 | 사용자와 직접 대화하며 워크플로를 제어하는 최상위 에이전트 |
| 병렬 실행(Parallel) | 여러 작업을 동시에 처리하는 방식. 독립적인 작업에 적합 |
| 직렬 실행(Serial) | 작업을 순차적으로 하나씩 처리하는 방식. 의존성 있는 작업에 적합 |
| 콘텍스트 윈도우 | AI가 한 번에 참조할 수 있는 텍스트의 최대 크기. 클로드는 200K 토큰(2025년 7월 기준) |
| 토큰(Token) | AI가 텍스트를 처리하는 기본 단위. 한국어 1글자는 약 2~3토큰 |
| Todo 리스트 | 클로드 코드가 작업 진행 상황을 체크박스로 표시하는 기능 |
| 프론트매터(Frontmatter) | 마크다운 파일 최상단 --- 사이의 메타데이터 영역 (name, description, color 등) |
| Git Worktree | 하나의 Git 저장소에서 여러 작업 디렉토리를 만드는 기능. 각 워크트리는 독립적인 브랜치에서 작업 |
| 머지 컨플릭트(Merge Conflict) | 두 브랜치에서 같은 파일의 같은 부분을 수정했을 때 Git이 자동으로 합치지 못하는 상황 |
| Auto Compact | 콘텍스트가 가득 차면 자동으로 요약하는 클로드 코드의 기능 |
| 할루시네이션(Hallucination) | AI가 사실이 아닌 내용을 마치 사실인 것처럼 생성하는 현상 |
부록 B: 비교표
서브에이전트 실행 방식 비교
| 비교 항목 | 병렬 실행 | 직렬 실행 |
|---|---|---|
| 실행 방식 | 여러 서브에이전트 동시 실행 | 서브에이전트를 하나씩 순차 실행 |
| 속도 | 빠름 (동시 처리) | 느림 (순차 처리) |
| 토큰 소비 | 많음 (에이전트 수 x 토큰) | 적음 (하나씩 사용) |
| 적합한 작업 | 독립적인 작업 (번역, 테스트) | 의존성 있는 작업 (CRUD 순차 개발) |
| 콘텍스트 관리 | 각 에이전트가 독립 콘텍스트 | 메인의 콘텍스트를 효율적으로 관리 |
| 대표 예시 | 4개 언어 동시 번역 | CRUD 엔드포인트 순차 개발 |
서브에이전트 vs 독립 에이전트
| 비교 항목 | 서브에이전트 | 독립 에이전트 |
|---|---|---|
| 생성 방식 | 메인에이전트가 생성 | 별도 터미널에서 직접 실행 |
| 관리 주체 | 메인에이전트가 워크플로 제어 | 사용자가 직접 관리 |
| 작업 환경 | 같은 프로젝트 디렉토리 | Git Worktree로 분리된 환경 |
| 결과 전달 | 메인에이전트에 자동 보고 | 별도로 merge 필요 |
| 적합한 상황 | 한 프로젝트 내 작업 분할 | 여러 프로젝트 또는 큰 기능 분리 |
| 충돌 위험 | 낮음 (메인이 관리) | 높음 (같은 파일 수정 가능) |
기본 서브에이전트 vs 커스텀 서브에이전트
| 비교 항목 | 기본 서브에이전트 | 커스텀 서브에이전트 |
|---|---|---|
| 생성 방법 | 클로드 코드가 자동 생성 | /agent 커맨드 또는 마크다운 파일 |
| 역할 | 범용 (general-purpose) | 특정 작업에 최적화 (테스트, 리뷰 등) |
| 설정 파일 | 없음 | .claude/agents/이름.md |
| 제약사항 | 없음 | 프롬프트로 "하면 안 되는 작업" 명시 가능 |
| 트리거 | 클로드가 필요 시 자동 생성 | description 기반 자동 트리거 또는 이름 명시 |
| 재사용 | 매번 새로 생성 | 한 번 만들면 반복 사용 |
부록 C: 참고 자료
- 클로드 코드 공식 문서 (서브에이전트): docs.anthropic.com -- 서브에이전트 생성 및 관리에 대한 공식 가이드
- Git Worktree 공식 문서: git-scm.com/docs/git-worktree -- Git Worktree 명령어 레퍼런스
- 코드팩토리 GitHub: github.com/codefactory-co -- 저자의 예제 코드 저장소
- 클로드 코드 완벽 가이드 유튜브: bit.ly/46EmBex -- 이 장의 내용을 다룬 유튜브 강의 영상
- 에이전틱 프로그래밍 개념: AI 에이전트가 자율적으로 코드를 작성/테스트/배포하는 패러다임. 서브에이전트는 이 패러다임의 핵심 도구
클릭하거나 Space를 눌러 뒤집기